ThreadView Control

Objects

Column Object, Columns Collection

ThreadLine Object, ThreadLines Collection

User Object

Properties
Columns	SelectedItem
Frozen	SortColumn
ImageList	SortOrder
Indentation	UserObject
ThreadLines
Methods
Refresh
Events
Collapse	HeaderMouseDown
Expand	HeaderMouseUp
HeaderClick	ItemClick
HeaderDblClick	ItemDblClick

Besides of this specific properties methods and events ThreadView control expose following standard ones:

DragMode, DragIcon, Container, Enabled, Name, Parent, Top, Visible, Width, Move, SetFocus, ShowWhatsThis, Zorder, Click, DblClick, KeyUp MouseMove.

See vb.hlp for help on these properties, methods or events.


Alignment Property

Returns or sets the alignment of text in a column.

Syntax

object.Alignment [= integer]

The Alignment Property syntax has these parts:

Part	Description

object	An object expression that evaluates to a Column object.

integer	An integer that determines the alignment, as described in Settings.

Settings

The settings for integer are:

Constant	Value	Description

vbAlignLeft	0	(Default) Left. Text is aligned left.

vbAlignRight	1	Right. Text is aligned right.

vbAlignCenter	2	Center. Text is centered.


Caption Property

Returns or sets the caption for a Column object.

Syntax

object.Caption [= string]

The Caption property syntax has these parts:

Part	Description

object	An object expression that evaluates to a Column object.

string	A string expression that evaluates to the text displayed as the caption.

Remarks

If you omit the Caption property, the Name property of Column object used as column header caption.


Index Property

Returns the number that uniquely identifies an object in a collection.

Syntax

object.Index

The object placeholder is an object expression that evaluates to a Column object. Columns are counted from left to right. The leftmost column has the Index=1, the rightmost has the Index = Columns.Count.

See Also

Count Property


Name Property

Returns/sets text associated with a column.

Syntax

object.Name[=string]

The Name property syntax has these parts:

Part	Description

object	An object expression that evaluates to a Column object.

string	A string expression that evaluates to the text associated with a column.

Remarks

This property used to retrieve data from User Object. ThreadView passes the Name property as a parameter to Properties method of the User Object. Changing the Name property at run-time forces the control to reread data and repaint itself.

See Also

Caption Property


Width Property

Return or set the width of a column in pixels.

Syntax

object.Width [= number]

The Width property syntax has these parts:

Part	Description

object	An object expression that evaluates to a Column object.

number	A numeric expression specifying the width of a column.

Remarks

If you want to temporarily hide a column set its Width property to 0.

User can change column width at run-time by dragging right border of a column header with the mouse.


Count property

Returns the number of members in a collection.

Syntax

object.Count

The object placeholder is an object expression that evaluates to Columns or ThreadLines collections.


Item Method

Returns a specific item of a collection object by index.

Syntax

object.Item(index)

The Item method syntax has these parts:

Part	Description

object	An object expression that evaluates to Columns or ThreadLines collections.

index	An integer that specifies a member of the collection. The integer must be a number from 1 to the value of the collection's Count property.

Remarks

If the value provided as index does not match any existing member of the collection, an error occurs.

The Item method is the default method for a collection. Therefore, the following lines of code are equivalent:

ThreadView1.Columns.Item(1)

ThreadView1.Columns(1)

See Also

Count Property


Add Method

Adds a Column object to a Columns collection.

Syntax

object.Add(Name As String, [Caption As String], [Width As Integer], [Alignment As Integer], [Position As Integer]))

The Add method syntax has these parts:

Part	Description

object	Required. An object expression that evaluates to a Columns collection.

Name	Required. A sting that identifies a member of a collection.

Caption	Optional. A string that appears in column header.

Width	Optional. A number that specifies the width of the column in pixels.

alignment	Optional. An integer that determines the alignment of text in the column. See the Alignment property for settings.

Position	Optional. An integer that specifies the position of a column in a collection.

Remarks

The Add method returns a reference to the newly inserted Column object.

Use the index argument to insert a column header in a specific position.

See Also

Index Property


Clear Method

Clears all objects in a collection.

Syntax

object.Clear

The object placeholder is an object expression that evaluates to Columns object.

Remarks

To remove one object from a collection, use the Remove method.


Remove Method

Removes a specific member from a collection.

Syntax

object.Remove index

The Remove method syntax has these parts:

Part	Description

object	An object expression that evaluates to Columns object.

index	An integer that identifies the object in the collection.

Remarks

To remove all the members of a collection, use the Clear method.

See Also

Index Property


Expanded Property

Returns or sets a value that determines whether a ThreadLine object in the control is currently expanded or collapsed.

Syntax

object.ThreadLines(index).Expanded[= boolean]

The Expanded property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

Index	Long integer that identifies a particular ThreadLine object within a ThreadLines collection.

boolean	A Boolean expression specifying whether the line is expanded or collapsed.

The settings for boolean are:

Setting	Description

True	The line is currently expanded.

False	The line is currently collapsed.

Remarks

You can use the Expanded property to programmatically expand or collapse a line. When Expanded property changed the Expand or Collapse event is generated. If a ThreadLine object has no child lines, the property value is ignored.

Example

ThreadView1.Lines(1).Expanded = True

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


Level Property

Returns a level of an object in a hierarchy of objects.

Syntax

object.ThreadLines(index).Level

The Level property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

Index	Long integer that identifies a ThreadLine object within a ThreadLines collection.

Remarks

If ThreadLine object is top-level object, then its Level property is 1.

Example

'loops thru ThreadLines and collapse all third-level lines

ThreadView1.Frozen = True

Do

    i = i + 1

    If ThreadView1.ThreadLines(i).Level >2 Then

        ThreadView1.ThreadLines(i).Expanded = False

    End If

Loop While ThreadView1.ThreadLines.Count > i

ThreadView1.Frozen = False

End Sub

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


Object Property

Returns a reference to an object associated with ThreadLine object.

Syntax

object.ThreadLines(index).Object

The Object property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

Index	Long integer that identifies a particular ThreadLine object within a ThreadLines collection.

Remarks

Each ThreadLine gets data from corresponding member of User Object. This property returns a reference to this member. You can use this property to access properties of the object.

Example

blnSheWasRight = ThreadView1.ThreadLines(1).Object Is objHerObject

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


Selected Property

Returns or sets a value that determines if a ThreadLine object is selected.

Syntax

object.ThreadLines(index).Selected [ = boolean]

The Selected property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

Index	Long integer that identifies a ThreadLine object within a ThreadLines collection.

boolean	A Boolean expression that determines if an object is selected.

Remarks

The Selected property is used to programmatically select a specific line.

Example

ThreadView1.ThreadLines(1).selected = True

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.

See Also

Move Method

MoveFirst Method

MoveLast Method

SelectedItem Property


EnsureVisible Method

Ensures that a specified ThreadLine object is visible. If necessary, this method scrolls the control.

Syntax

object.ThreadLines(index).EnsureVisible

The EnsureVisible method syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

Index	Long integer that identifies a particular ThreadLine object within a ThreadLines collection.

Return Values

Value	Description

True	The method returns True if the control must scroll to expose the object.

False	The method returns False if no scrolling is required.

Remarks

Use the EnsureVisible method when you want a particular ThreadLine object, which might be hidden deep in the control, to be visible.

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


Move Method

Moves the position of a selection to specified number of lines and returns reference to newly selected ThreadLine object.

Syntax

object.Move offset

The Move method syntax has these parts:

Part	Description

object	An Object expression that evaluates to a ThreadLine object.

offset	A signed Long value specifying the number of lines the selection will move. If offset is greater than 0, the selection is moved forward. If offset is less than 0, the selection is moved backward.

Remarks

If using of this method will move the selection before the first or after the last line in the control, this method returns Nothing. Selection remains unchanged. If you want to move to the first or to the last line use MoveFirst or MoveLast methods.

This method does not make selected ThreadLine object visible. If you want to do so, use EnsureVisible method as in the following example:

ThreadView1.ThreadLines.Move(20).EnsureVisible

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.

See Also

SelectedItem Property

Selected Property


MoveFirst, MoveLast Methods

Moves the position of a selection to the first or to the last line and returns reference to newly selected ThreadLine object.

Syntax

Object.{MoveFirst|MoveLast}

The object placeholder represents the object expression that evaluates to ThreadLines object.

Remarks

These methods do not make selected ThreadLine object visible. If you want to do so, use EnsureVisible method. If you want to move the selection from the current line to the particular line, use Move method.

Example

blnExp = ThreadView1.ThreadLines.MoveLast.Expanded

ThreadView1.ThreadLines.MoveFirst.EnsureVisible

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.

See Also

SelectedItem Property

Selected Property


Columns Property

Returns a reference to a collection of Column objects.

Syntax

object.Columns

The object placeholder represents an object expression that evaluates to a ThreadView control.

See Also

Column Object, Columns Collection


Frozen Property

Returns a value indicating if the control is currently stops repainting itself.

Syntax

object.Frozen [= boolean]

The Frozen property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

boolean	A Boolean expression specifying whether the object is visible or hidden, as described in Settings.

Settings

The settings for boolean are:

Setting	Description

True	ThreadView does not repaint itself.

False	ThreadView repaints itself.

Remarks

Always set this property to True when you add or remove column columns, set UserObject property or make batch changes to the control. This will speeds up most actions.

Example

With ThreadView1

.Frozen = True

With .Columns

.Add "First"

.Add "Second"

End With

.Frozen = False

End With


ImageList Property

Returns or sets the ImageList control to be used with a ThreadView control.

Syntax

object.ImageList [= imagelist]

The ImageList property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

imagelist	An object reference that specifies which ImageList control to use.

Remarks

Images in ImageList control are used by ThreadView control to draw icons on each line. To use it first place ImageList control on the form and fill it with the images. Images should be 16x16 pixels icons or bitmaps. Then, at run-time, set ImageList property of the ThreadView control to this ImageList control.

Example

Set ThreadView1.ImageList = Form1.ImageList1

See Also

Creating User Object


Indentation Property

Returns/sets the width of the indentation for the control in pixels.

Syntax

object.Indentation[ = number]

The Indentation property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

number	An integer specifying the width that each child ThreadLine is indented.

Remarks

Default value is 15 pixels. The property value cannot be negative.

Example

ThreadView1.Indentation = 30


ThreadLines Property

Returns a reference to a collection of ThreadLine objects.

Syntax

object.ThreadLines

The object placeholder represents an object expression that evaluates to a ThreadView control.


SelectedItem Property

Returns a reference to the selected ThreadLine object in the control.

Syntax

object.SelectedItem

The object placeholder represents an object expression that evaluates to ThreadView control.

Remarks

SelectedItem changes when you use Move methods.

Example

Private Sub Command1_Click()

ThreadView1.SelectedItem.Expanded = True

End Sub

Warning	Never store a reference to a particular ThreadLine object in an object variable. Use full syntax instead.

See Also

Selected Property

Move Method

MoveFirst Method

MoveLast Method


SortColumn Property

Returns or sets a column that shown with a sort triangle inside.

Syntax

object.SortColumn [= integer]

The SortColumn property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

integer	An integer specifying the index of the Column object in the Columns collection, must be from 0 to Columns.Count.

Remarks

When SortColumn property is 0 no column header shown with sort triangle.

ThreadView does not actually sorts its contents. This property controls the existence of sort triangle inside a header of a specified Column object. The direction of the triangle (up or down) is controlled by SortOrder property.

Example

'shows sort triangle in last column header

ThreadView1.SortColumn = ThreadView1.Columns.Count


SortOrder Property

Returns or sets a direction of sort triangle in a sort column header.

Syntax

object.SortOrder [= integer]

The SortOrder property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

integer	An integer specifying the direction of the sort rectangle as described in Settings.

Settings

The settings for integer are:

Constant	Value	Description

thvSortAsc	0	Sort rectangle shown "up".

thvSortDesc	1	Sort rectangle shown "down".

Remarks

ThreadView does not actually sorts data. This property controls the direction of the triangle (up or down). The existence of sort triangle inside a header of a specified Column object is controlled by SortColumn property.

Example

ThreadView1.SortOrder = thvSortDesc


UserObject Property

Returns/sets object with data provided by user of a control.

Syntax

object.UserObject [= userobject]

The UserObject property syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

userobject	An object reference that evaluates to an object with data.

Remarks

UserObject property is a key part of ThreadView control interface. The control get data to display from object set in this property.

Example

Set ThreadView1.UserObject = objContacts

See Also

Creating User Object.


Collapse Event

Occurs when a ThreadLine object in a ThreadView control is collapsed.

Syntax

Private Sub object_Collapse(ByVal ThreadLine As ThreadLine)

The Collapse event syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

ThreadLine	A reference to the collapsed ThreadLine object.

Remarks

There are three methods of collapsing a ThreadLine: by setting the ThreadLine object's Expanded property to False, by pressing left arrow button when expanded ThreadLine object is selected, and by clicking a plus/minus icon. All of these methods generate the Collapse event. You can use this event to free up memory by removing references to child objects of collapsed line.

Example

'This code removes references to

'subitems of collapsed line object

Private Sub ThreadView1_Collapse(ByVal ThreadLine As ThreadLine)

Set ThreadLine.Object.Children = Nothing

End Sub

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


Expand Event

Occurs when a ThreadLine object in a ThreadView control is expanded.

Syntax

Sub object_Expand (ByVal ThreadLine As ThreadLine)

The Expand event syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

ThreadLine	A reference to the expanded ThreadLine object.

Remarks

There are three methods of expanding a ThreadLine object that has child objects: by setting the ThreadLine object's Expanded property to True, by pressing right arrow button when collapsed ThreadLine object is selected, and by clicking a plus/minus icon. All of these methods generate the Collapse event.

Example

Private Sub ThreadView1_Expand (ByVal ThreadLine As ThreadLine)

If ThreadLine.Object.Children(1).Bonus Then PlayFanfares

End Sub

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


HeaderClick, HeaderDblClick Events

Occurs when the user clicks or double-clicks on the header of a column.

Syntax

Private Sub object_HeaderClick (Column As ThreadViewAX.Column)

Private Sub object_HeaderDblClick (Column As ThreadViewAX.Column)

The HeaderClick and HeaderDblClick events syntax has these parts:

Part	Description

object	An object expression that evaluates to ThreadView control.

Column	A reference to clicked column object.

Remarks

You can use HeaderClick event to change the SortOrder and SortColumn properties. You can use HeaderDblClick event to show pop-up form where user can choose which columns to display. If you want to determine which mouse button was pressed, use HeaderMouseDown or HeaderMouseUp events.

Example

Private Sub ThreadView1_HeaderClick(Column As ThreadViewAX.Column)

With ThreadView1

    If .SortColumn = Column.Index Then

        .SortOrder = Abs(Not CBool(.SortOrder))

      Else

        .SortColumn = Column.Index

    End If

End With

End Sub

Private Sub ThreadView1_HeaderDblClick(Column As ThreadViewAX.Column)

    MsgBox "To add or remove columns go to Tools/Options menu"

End Sub


HeaderMouseDown, HeaderMouseUp Events

Occur when the user presses (HeaderMouseDown) or releases (HeaderMouseUp) a mouse button.

Syntax

Private Sub object_HeaderMouseDown(button As Integer, shift As Integer, x As Single, y As Single)

Private Sub object _HeaderMouseUp(button As Integer, shift As Integer, x As Single, y As Single)

The HeaderMouseDown and HeaderMouseUp event syntax have these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

button, shift, x, y	Same as corresponding arguments in standard MouseDown and MouseUp events. See vb.hlp for more info.

Remarks

You can use HeaderMouseDown event to show pop-up menu for changing sort order of pressed column.

Example

Private Sub ThreadView1_HeaderMouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)

Dim i As Long, lngWidth As Long

If (Button And vbRightButton) = vbRightButton Then

    For i = 1 To ThreadView1.Columns.Count

        'calculates which column was pressed by comparing

        'X argument with column width.

        lngWidth = lngWidth + ThreadView1.Columns(i).Width

        If lngWidth >= X Then

            'sets module level variable to pressed column index

            lngCurColumn = i

            Exit For

        End If

    Next I

    PopupMenu mnuPopUpHeader, vbPopupMenuRightButton

    'Method of mnuPopUpHeader does something with lngCurColumn

End If

End Sub

See Also

HeaderClick Event

HeaderDblClick Event


ItemClick, ItemDblClick Events

Occurs when a ThreadLine object in a ThreadView control is clicked or double-clicked.

Syntax

Private Sub object_ItemClick(Line As ThreadViewAX.ThreadLine)

Private Sub object_ItemDblClick(Line As ThreadViewAX.ThreadLine)

The ItemClick and ItemDblClick events syntax has these parts:

Part	Description

object	An object expression that evaluates to a ThreadView control.

Line	The ThreadLine object that was clicked or double-clicked.

Remarks

ItemClick event generates when user press up or down arrows also.

Use this events to determine which ThreadLine object was clicked. This event is triggered before the Click event. The standard Click and DblClick events are generated if the mouse is clicked on any part of the ThreadView control. The ItemClick or ItemDblClick events are generated only when the mouse is clicked on the text or image of a ThreadLine object.

Example

'shows message body in preview pane

Private Sub ThreadView1_ItemClick(Line As ThreadViewAX.ThreadLine)

    txtPreviewPane.Text = Line.Object.MessageBody

End Sub

'opens form for message

Private Sub ThreadView1_ItemDblClick(Line As ThreadViewAX.ThreadLine)

    With frmMessage

        .txtMessageBody = Line.Object.MessageBody

        .txtSubject = Line.Object.Subject

        .txtAuthor = Line.Object.Author

        .Show

    End With

End Sub

Warning	Never store reference to a particular ThreadLine object in an object variable. Use full syntax instead.


Column Object, Columns Collection

Column object represents a column within a ThreadView control.

Columns collection contains all Column objects of a ThreadView control.

Properties (Object)

Alignment	Name
Caption	Width
Index

Properties (Collection)

Count	Item

Methods (collection)

Add	Remove
Clear


ThreadLine Object, ThreadLines Collection

ThreadLine object represents a line within a ThreadView control.

ThreadLines collection contains all ThreadLine objects of a ThreadView control.

Properties (Object)

Expanded	Object
Level	Selected

Methods (Object)

EnsureVisible

Properties (Collection)

Count	Item

Methods (Collection)

MoveFirst	Move
MoveLast


Refresh Method

Forces a complete repaint of a control.

Syntax

object.Refresh

The object placeholder represents an object expression that evaluates to ThreadView control.

Remarks

You can use this method to update the display. For example, when you change Image property of an object of a visible line, you will not see changes immediately. Use Refresh method to redraw contents of a ThreadView control.


Property Page
ThreadView Property Page


Creating User Object

Provides ThreadView control with data.

ThreadView is responsible only for displaying data. You, as developer, should provide it with a special data object, called User Object. User Object must be created from at list two classes: Collection Class and Item Class. Collection Class can be the generic VB collection object.

Collection Class should implement:

•	Count property

This property returns total numbers of members in a collection.

•	Item method

Syntax: Object.Item(index as Long) As Object (Item Class)

This method returns a reference to a particular member of a collection.

Item Class should implement:

•	Image Property

This property returns an index or a key of a ListImage object in an associated ImageList control. ThreadView control uses this ListImage object to draw the icon.

•	HasChildren Property

This property returns a boolean value which used by ThreadView to draw plus/minus icon.

•	Children Property

This property returns a reference to an object instantiated from Collection Class. This object should contain child objects.

•	Properties method

Syntax: Object.Properties(PropName as String) As Variant

This property returns a data ThreadView control should draw on screen. ThreadView control read value from a Name property of each Column object and then calls Properties method with this value as a parameter.

Example

Add class module to a project and name it clsMessage. Put the following code in clsMessage:

Public Body As String

Public Author As String

Public Image

Public HasChildren As Boolean

Public Children As New Collection

Public Function Properties(value)

Select Case value

    Case "Body"

        Properties = Body

    Case "Author"

        Properties = Author

End Select

End Function

Following code initialize User Object. Put it anywhere you want.

' Using intrinsic VB collection object as the User Object

Dim colMessages as New Collection

Dim X As clsMessage

Set X = New clsMessage

X.Body = "This is the sample of Message text"

X.Author = "Anonymous"

X.Image = "UnreadMsg"

'if images in associated ImageList haven't keys, use integer indexes

colMessages.Add X

Set X = New clsMessage

X.Body = "This is the child of the first Message"

X.Author = "Anonymous' Child"

X.Image = 2

colMessages(1).Children.Add X

Now you are ready to set UserObject property of ThreadView control to colMessages.